                    Fileset Menu

Filesets are lists of files that Alpha uses for multiple-file searches and 
tag searches, among other things.  Typically, a user will set up several 
different file sets, perhaps one specifying all the source files in a 
project, another specifying all the Mac include files, and another 
specifying all the UNIX include files, and yet another one with all html 
files in a home page.

Activating the Fileset menu

The Filesets menu is activated in the dialog "Config->Preferences->Menus
and Features" Check the checkbox 'Fileset Menu' among the global menus.

Getting started

As an introductory example this section describes how to create a new 
fileset with all files in a folder.
 Create a new fileset by selecting 'New Fileset' in the Utilities submenu 
of the Fileset Menu.
 You are now asked which type of fileset you want. Select the 
'fromDirectory' to create a fileset with the files in a folder.
 You are now asked to give the fileset a name. Let's give it the name 'My 
fileset'.
 Then you are asked to select the folder for the fileset.
 Next you asked to give a pattern for the fileset specifying which files 
to include in the folder to include in the fileset. To include file use the 
default pattern '*'. See the section File Patterns in the Alpha manual to 
learn about how to specify file patterns.
 Next you are asked to specify a list of patterns for files you want to 
exclude from the fileset but which was included by the file pattern you 
just specified. Leave this blank for now.
 Finally you are asked if you want save the fileset. Doing so will make 
Alpha keep the fileset next time you run Alpha.

Alpha now builds a new submenu of the Fileset menu called 'My fileset' with 
all you files in the folder. Selecting a file in the submenu will open the 
file in Alpha.

Your fileset can also be used for multi-file searching. In the Find dialog 
when selecting multi file searching, you can choose to search the files in 
your fileset.

You can also do multi file search and replace in your fileset, by 
selecting 'Replace In Fileset' in the Utilities menu.

Fileset types

Some fileset types require that you give file patterns specifying which 
files to include in the fileset. Read the Section File Patterns in the 
Alpha manual to learn about how to specify file patterns.

From Directory          The basic type: create a fileset of all files in a
                        given folder which match a given pattern. You have to 
                        specify:
                         The folder with the files.
                         A file pattern matching the files to include.
                         A list of patterns of files to exclude.
                        
From Hierarchy          Takes the above one step further and allows filesets
                        to include all files in a nested set of folders.
                        You have to specify:
                         The base folder with the files.
                         The depth of nested folders.
                         A file pattern matching the files to include.
                        
From Open Windows       Make a fileset containing all currently open windows.

Codewarrior             Query the Codewarrior IDE for a list of all files in
                        the current project.
                        
Think                   Query the Symantec Project Manager for a list of all
                        files in the current project.

Tex                     Make a fileset of all parts of a multi-part 
                        TeX/LaTeX document. Alpha's LaTeX mode understands 
                        these and will automatically send your TeX 
                        application the base .tex/.ltx file when you select 
                        'Typeset' on any component part. Details about TeX 
                        filesets can be found in the LaTeX mode 
                        documentation.

Ftp                     Make a fileset of files at a remote machine via 
                        ftp. You have to specify:
                         Host, path (optional), user id, and password
                         A regular expression (not a file pattern!) 
                        matching the files to include.

Procedural              Make a fileset from a Tcl procedure. This type 
                        requires that you write a Tcl procedure which 
                        returns a list of paths to all files in the 
                        fileset. When you create a new procedural fileset 
                        Alpha puts an empty procedure (with the correct 
                        name!) in your global preferences file. You must 
                        then write the body of this procedure. Procedural 
                        filesets are completely dynamic and will not appear 
                        in the Fileset menu.

The following items will be added to the utilities menu if you use 
TeX filesets:

Extract Eps BoxSizes    search all document parts for included eps graphics,  
                        extract bounding box information from the .eps files 
                        and insert it explicitly into the document (can lead 
                        to much quicker typesetting).
                        
Delete Eps Box Sizes    remove all the above bounding box information

Hierarchical Bib Files  bibliography files may \input others, so they should
                        be searched (the default is not to do this, because
                        .bib files may be enormous).

Non-text files

By default only text files are included in the fileset. If the flag 
'Include Non Text Files' is set, the fileset menu may contain files Alpha 
is not designed to open; these are sent to the Finder which will open them 
using whichever application created them.  A common use of this feature is 
a hierarchical fileset containing a complete C or C++ project.  Selecting any 
project source file will open that file for editing, and selecting the 
project file/debugging symbol file/... will open that using appropriate 
tool (Symantec Project Manager or Codewarrior IDE or Debugger,) 
Another use can be to include images in a home page so you can quickly 
open them when you want to change the graphics.

Fileset cache

Rather than rebuilding the Fileset menu every time you launch Alpha, the 
menu is saved in a cache file. This is to speed up launching of Alpha as 
building the filesets may take a while if there are many of them. Therefore 
the fileset submenus may become out of date and you have to rebuild them. 
You can rebuild a single fileset either using 'Update Current Fileset' or 
'Update A Fileset' or rebuild them all using 'Rebuild All Filesets'.

Current Fileset

Some functions that use filesets operate on the 'current' fileset. The 
current file set can be selected in the 'Choose' submenu of the Utilities 
menu. There is also a flag 'Auto Adjust Fileset' which will switch the 
current filesets whenever the fileset menu is used to open a file.



Fileset Utilities

The fileset utilities menu contains the following items:

New Fileset            create a new fileset of one of the above six 
                        standard types (others may be added by writing your 
                        own Tcl code, see below.)

Delete Fileset         remove a fileset, permanently if desired.

Print Fileset          print all files in a fileset

Update Current Fileset  re-build the current fileset from scratch

Update A Fileset        (hold down option) lets you choose a fileset to 
                        rebuild.

Rebuild All Filesets    total menu rebuild.

Zap And Build Filesets  (hold down option) a more drastic version of the 
                        above.

Choose                  a menu from which to set the current fileset.

Hide Fileset            if you have many filesets, some of which are only 
                        used for searching purposes, you can remove them 
                        from the menu.
                        
Fileset Flags           see below for an explanation of the flags.   

Find Tag                see Tags for information on this and the 
                        following item.
Create Tag File 

The items below may not all work for all types of filesets.

Browse Fileset         opens a browser window containing all fileset items, 
                        from which any can be opened.
                        
Close Entire Fileset   close all windows which belong to a given fileset.

Fileset To Alpha       convert all text files in a fileset to Alpha's creator.

Open Entire Fileset    open all files in a fileset

Open Fileset Folder    tells the Finder to open the base folder which 
                        contains a fileset.
                        
Rename Fileset         change a fileset's name

Replace In Fileset     global search and replace in all files. Use this 
                        item with care!
                        
Stuff Fileset          If you have 'DropStuff' installed, you can archive a 
                        fileset.
                        
Word Count              Count all words in a fileset 

The following flags may be set:

Auto Adjust Fileset     opening a file from the menu will adjust current 
                        fileset

Include Non Text Files  files not of type 'TEXT' may be in the menu.

Indent Fileset Items    visually format submenus if appropriate.

Sort Fileset Items      force alphabetical ordering for all filesets

Sort Filesets By Type   structure the fileset menu in a user-defined, type-
                        dependent fashion; see Personalisation.


Personalisation

As well as adjusting the aforementioned flags, the fileset menu allows 
complete user control of the structure of the menu in the following way: 
Set the 'Sort Filesets By Type' flag, and set the variable 
"filesetSortOrder" as follows:

   The structure of this variable dictates how the fileset
   menu is structured:
       
       '{pattern p}' 
           lists all filesets which match 'p'
       '-' 
           adds a separator line
       '{list of types}' 
           lists all filesets of those types.
       '{submenu name sub-order-list}' 
           adds a submenu with name 'name' and recursively
           adds filesets to that submenu as given by the 
           sub-order.
           
   Leading, trailing and double separators are automatically
   removed.

For example, the default value of this variable (more as an example than 
anything else) is:

set filesetSortOrder { {pattern *System} {pattern Packages} \
                        {pattern Menus} {pattern Modes} {pattern Preferences} \
                        - {tex} - {pattern *.cc} {submenu Headers {pattern *.h}} \
                        - {fromDirectory think codewarrior ftp \
                        fromOpenWindows fromHierarchy} * }
                        
You can and should over-ride this in your global preferences file (copy and 
paste from here, then make your changes).

